/**
 * SPDX-FileCopyrightText: 2021-2024 Infineon Technologies AG
 * SPDX-License-Identifier: MIT
 *
 * \author Infineon Technologies AG
 *
 * \file ifx_i2c_data_link_layer.h
 *
 * \brief   This file defines the API prototype for data link layer of the Infineon I2C Protocol Stack library.
 *
 * \ingroup  grIFXI2C
 *
 * @{
 */

#ifndef _IFX_I2C_DATA_LINK_LAYER_H_
#define _IFX_I2C_DATA_LINK_LAYER_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "ifx_i2c_config.h"

/** @brief Error event propagated to upper layer */
#define IFX_I2C_DL_EVENT_ERROR (0x01)
/** @brief Transmit success event propagated to upper layer (bit field 1) */
#define IFX_I2C_DL_EVENT_TX_SUCCESS (0x02)
/** @brief Receive success event propagated to upper layer (bit field 3)*/
#define IFX_I2C_DL_EVENT_RX_SUCCESS (0x04)

/**
 * \brief Function for initializing the module
 *
 * \details
 * Function initializes and enables the module and registers an event handler to receive events from this module.
 *
 * \pre
 * - This function must be called before using the module.
 *
 * \note
 * - None
 *
 * \param[in,out] p_ctx                    Pointer to ifx i2c context.
 * \param[in]     handler                  Function pointer to the event handler of the upper layer.
 *
 * \retval        IFX_I2C_STACK_SUCCESS    If initialization was successful.
 * \retval        IFX_I2C_STACK_ERROR      If the module is already initialized.
 */
optiga_lib_status_t ifx_i2c_dl_init(ifx_i2c_context_t *p_ctx, ifx_i2c_event_handler_t handler);

/**
 * \brief Function for sending a frame
 *
 * \details
 * Asynchronous function to send a frame
 * - The function returns immediately.
 * - One of the following events is propagated to the event handler registered with #ifx_i2c_dl_init.
 *
 * \pre
 * - None
 *
 * \note
 * - None
 *
 * \param[in,out]   p_ctx                   Pointer to ifx i2c context.
 * \param[in]       frame_len               Frame length.
 *
 * \retval          IFX_I2C_STACK_SUCCESS   If function was successful.
 * \retval          IFX_I2C_STACK_ERROR     If the module is busy.
 */
optiga_lib_status_t ifx_i2c_dl_send_frame(ifx_i2c_context_t *p_ctx, uint16_t frame_len);

/**
 * \brief Function for receiving a frame
 *
 * \details
 * Asynchronous function to receive a frame
 * - The function returns immediately.
 * - One of the following events is propagated to the event handler registered with #ifx_i2c_dl_init.
 *
 * \pre
 * - None
 *
 * \note
 * - None
 *
 * \param[in,out] p_ctx                   Pointer to ifx i2c context.
 *
 * \retval        IFX_I2C_STACK_SUCCESS   If function was successful.
 * \retval        IFX_I2C_STACK_ERROR     If the module is busy.
 */
optiga_lib_status_t ifx_i2c_dl_receive_frame(ifx_i2c_context_t *p_ctx);

#ifdef __cplusplus
}
#endif

#endif /* _IFX_I2C_DATA_LINK_LAYER_H_ */

/**
 * @}
 **/
